home *** CD-ROM | disk | FTP | other *** search
/ Chip 2007 January, February, March & April / Chip-Cover-CD-2007-02.iso / Pakiet bezpieczenstwa / mini Pentoo LiveCD 2006.1 / mpentoo-2006.1.iso / livecd.squashfs / usr / lib / mozilla-firefox / idl / nsIProtocolProxyService.idl < prev    next >
Text File  |  2006-05-08  |  10KB  |  227 lines
  1. /* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
  2. /* vim:set ts=4 sw=4 sts=4 et: */
  3. /* ***** BEGIN LICENSE BLOCK *****
  4.  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
  5.  *
  6.  * The contents of this file are subject to the Mozilla Public License Version
  7.  * 1.1 (the "License"); you may not use this file except in compliance with
  8.  * the License. You may obtain a copy of the License at
  9.  * http://www.mozilla.org/MPL/
  10.  *
  11.  * Software distributed under the License is distributed on an "AS IS" basis,
  12.  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  13.  * for the specific language governing rights and limitations under the
  14.  * License.
  15.  *
  16.  * The Original Code is mozilla.org code.
  17.  *
  18.  * The Initial Developer of the Original Code is
  19.  * Netscape Communications Corporation.
  20.  * Portions created by the Initial Developer are Copyright (C) 1998
  21.  * the Initial Developer. All Rights Reserved.
  22.  *
  23.  * Contributor(s):
  24.  *   Darin Fisher <darin@meer.net>
  25.  *
  26.  * Alternatively, the contents of this file may be used under the terms of
  27.  * either the GNU General Public License Version 2 or later (the "GPL"), or
  28.  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  29.  * in which case the provisions of the GPL or the LGPL are applicable instead
  30.  * of those above. If you wish to allow use of your version of this file only
  31.  * under the terms of either the GPL or the LGPL, and not to allow others to
  32.  * use your version of this file under the terms of the MPL, indicate your
  33.  * decision by deleting the provisions above and replace them with the notice
  34.  * and other provisions required by the GPL or the LGPL. If you do not delete
  35.  * the provisions above, a recipient may use your version of this file under
  36.  * the terms of any one of the MPL, the GPL or the LGPL.
  37.  *
  38.  * ***** END LICENSE BLOCK ***** */
  39.  
  40. #include "nsISupports.idl"
  41.  
  42. interface nsICancelable;
  43. interface nsIProtocolProxyCallback;
  44. interface nsIProtocolProxyFilter;
  45. interface nsIProxyInfo;
  46. interface nsIChannel;
  47. interface nsIURI;
  48.  
  49. /**
  50.  * nsIProtocolProxyService provides methods to access information about
  51.  * various network proxies.
  52.  *
  53.  * @status UNDER_REVIEW
  54.  */
  55. [scriptable, uuid(e38ab577-786e-4a7f-936b-7ae4c7d877b2)]
  56. interface nsIProtocolProxyService : nsISupports
  57. {
  58.     /**
  59.      * This flag may be passed to the resolve method to request that it fail
  60.      * instead of block the calling thread.  Proxy Auto Config (PAC) may
  61.      * perform a synchronous DNS query, which may not return immediately.  So,
  62.      * calling resolve without this flag may result in locking up the calling
  63.      * thread for a lengthy period of time.
  64.      *
  65.      * By passing this flag to resolve, one can failover to asyncResolve to
  66.      * avoid locking up the calling thread if a PAC query is required.
  67.      *
  68.      * When this flag is passed to resolve, resolve may throw the exception
  69.      * NS_BASE_STREAM_WOULD_BLOCK to indicate that it failed due to this flag
  70.      * being present.
  71.      */
  72.     const unsigned long RESOLVE_NON_BLOCKING = 1;
  73.     
  74.     /**
  75.      * This method returns a nsIProxyInfo instance that identifies a proxy to
  76.      * be used for loading the given URI.  Otherwise, this method returns null
  77.      * indicating that a direct connection should be used.
  78.      *
  79.      * @param aURI
  80.      *        The URI to test.
  81.      * @param aFlags
  82.      *        A bit-wise OR of the RESOLVE_ flags defined above.  Pass 0 to
  83.      *        specify the default behavior.
  84.      *
  85.      * NOTE: If this proxy is unavailable, getFailoverForProxy may be called
  86.      * to determine the correct secondary proxy to be used.
  87.      *
  88.      * NOTE: If the protocol handler for the given URI supports
  89.      * nsIProxiedProtocolHandler, then the nsIProxyInfo instance returned from
  90.      * resolve may be passed to the newProxiedChannel method to create a
  91.      * nsIChannel to the given URI that uses the specified proxy.
  92.      *
  93.      * NOTE: However, if the nsIProxyInfo type is "http", then it means that
  94.      * the given URI should be loaded using the HTTP protocol handler, which
  95.      * also supports nsIProxiedProtocolHandler.
  96.      *
  97.      * NOTE: If PAC is configured, and the PAC file has not yet been loaded,
  98.      * then this method will return a nsIProxyInfo instance with a type of
  99.      * "unknown" to indicate to the consumer that asyncResolve should be used
  100.      * to wait for the PAC file to finish loading.  Otherwise, the consumer
  101.      * may choose to treat the result as type "direct" if desired.
  102.      *
  103.      * @see nsIProxiedProtocolHandler::newProxiedChannel 
  104.      */
  105.     nsIProxyInfo resolve(in nsIURI aURI, in unsigned long aFlags);
  106.  
  107.     /**
  108.      * This method is an asychronous version of the resolve method.  Unlike
  109.      * resolve, this method is guaranteed not to block the calling thread
  110.      * waiting for DNS queries to complete.  This method is intended as a
  111.      * substitute for resolve when the result is not needed immediately.
  112.      *
  113.      * @param aURI
  114.      *        The URI to test.
  115.      * @param aFlags
  116.      *        A bit-wise OR of the RESOLVE_ flags defined above.  Pass 0 to
  117.      *        specify the default behavior.
  118.      * @param aCallback
  119.      *        The object to be notified when the result is available.
  120.      *
  121.      * @return An object that can be used to cancel the asychronous operation.
  122.      */
  123.     nsICancelable asyncResolve(in nsIURI aURI, in unsigned long aFlags,
  124.                                in nsIProtocolProxyCallback aCallback);
  125.  
  126.     /**
  127.      * This method may be called to construct a nsIProxyInfo instance from
  128.      * the given parameters.  This method may be useful in conjunction with
  129.      * nsISocketTransportService::createTransport for creating, for example,
  130.      * a SOCKS connection.
  131.      *
  132.      * @param aType
  133.      *        The proxy type.  This is a string value that identifies the proxy
  134.      *        type.  Standard values include:
  135.      *          "http"    - specifies a HTTP proxy
  136.      *          "socks"   - specifies a SOCKS version 5 proxy
  137.      *          "socks4"  - specifies a SOCKS version 4 proxy
  138.      *          "direct"  - specifies a direct connection (useful for failover)
  139.      *        The type name is case-insensitive.  Other string values may be
  140.      *        possible.
  141.      * @param aHost
  142.      *        The proxy hostname or IP address.
  143.      * @param aPort
  144.      *        The proxy port.
  145.      * @param aFlags
  146.      *        Flags associated with this connection.  See nsIProxyInfo.idl
  147.      *        for currently defined flags.
  148.      * @param aFailoverTimeout
  149.      *        Specifies the length of time (in seconds) to ignore this proxy if
  150.      *        this proxy fails.  Pass PR_UINT32_MAX to specify the default
  151.      *        timeout value, causing nsIProxyInfo::failoverTimeout to be
  152.      *        assigned the default value.
  153.      * @param aFailoverProxy
  154.      *        Specifies the next proxy to try if this proxy fails.  This
  155.      *        parameter may be null.
  156.      */
  157.     nsIProxyInfo newProxyInfo(in ACString aType, in AUTF8String aHost,
  158.                               in long aPort, in unsigned long aFlags,
  159.                               in unsigned long aFailoverTimeout,
  160.                               in nsIProxyInfo aFailoverProxy);
  161.  
  162.     /**
  163.      * If the proxy identified by aProxyInfo is unavailable for some reason,
  164.      * this method may be called to access an alternate proxy that may be used
  165.      * instead.  As a side-effect, this method may affect future result values
  166.      * from resolve/asyncResolve as well as from getFailoverForProxy.
  167.      *
  168.      * @param aProxyInfo
  169.      *        The proxy that was unavailable.
  170.      * @param aURI
  171.      *        The URI that was originally passed to resolve/asyncResolve.
  172.      * @param aReason
  173.      *        The error code corresponding to the proxy failure.  This value
  174.      *        may be used to tune the delay before this proxy is used again.
  175.      *
  176.      * @throw NS_ERROR_NOT_AVAILABLE if there is no alternate proxy available.
  177.      */
  178.     nsIProxyInfo getFailoverForProxy(in nsIProxyInfo aProxyInfo,
  179.                                      in nsIURI       aURI,
  180.                                      in nsresult     aReason);
  181.  
  182.     /**
  183.      * This method may be used to register a proxy filter instance.  Each proxy
  184.      * filter is registered with an associated position that determines the
  185.      * order in which the filters are applied (starting from position 0).  When
  186.      * resolve/asyncResolve is called, it generates a list of proxies for the
  187.      * given URI, and then it applies the proxy filters.  The filters have the
  188.      * opportunity to modify the list of proxies.
  189.      *
  190.      * If two filters register for the same position, then the filters will be
  191.      * visited in the order in which they were registered.
  192.      *
  193.      * If the filter is already registered, then its position will be updated.
  194.      *
  195.      * After filters have been run, any disabled or disallowed proxies will be
  196.      * removed from the list.  A proxy is disabled if it had previously failed-
  197.      * over to another proxy (see getFailoverForProxy).  A proxy is disallowed,
  198.      * for example, if it is a HTTP proxy and the nsIProtocolHandler for the
  199.      * queried URI does not permit proxying via HTTP.
  200.      *
  201.      * If a nsIProtocolHandler disallows all proxying, then filters will never
  202.      * have a chance to intercept proxy requests for such URLs.
  203.      *
  204.      * @param aFilter
  205.      *        The nsIProtocolProxyFilter instance to be registered.
  206.      * @param aPosition
  207.      *        The position of the filter.
  208.      *
  209.      * NOTE: It is possible to construct filters that compete with one another
  210.      * in undesirable ways.  This API does not attempt to protect against such
  211.      * problems.  It is recommended that any extensions that choose to call
  212.      * this method make their position value configurable at runtime (perhaps
  213.      * via the preferences service).
  214.      */
  215.     void registerFilter(in nsIProtocolProxyFilter aFilter,
  216.                         in unsigned long aPosition);
  217.  
  218.     /**
  219.      * This method may be used to unregister a proxy filter instance.  All
  220.      * filters will be automatically unregistered at XPCOM shutdown.
  221.      *
  222.      * @param aFilter
  223.      *        The nsIProtocolProxyFilter instance to be unregistered.
  224.      */
  225.     void unregisterFilter(in nsIProtocolProxyFilter aFilter);
  226. };
  227.